package cn.iocoder.yudao.module.reading.service.favorite;

import cn.iocoder.yudao.framework.common.pojo.PageParam;
import cn.iocoder.yudao.framework.common.pojo.PageResult;
import cn.iocoder.yudao.module.reading.controller.app.favorite.vo.FavoriteCreateReqVO;
import cn.iocoder.yudao.module.reading.controller.app.favorite.vo.FavoriteRespVO;
import cn.iocoder.yudao.module.reading.controller.app.favorite.vo.FavoriteItemRespVO;

import java.util.List;
import java.util.Map;

/**
 * 收藏管理 Service 接口
 *
 * @author 李晨
 */
public interface FavoriteService {

    /**
     * 添加收藏
     *
     * @param userId      用户ID
     * @param createReqVO 收藏信息
     * @return 收藏ID
     */
    Long addFavorite(Long userId, FavoriteCreateReqVO createReqVO);

    /**
     * 取消收藏
     *
     * @param userId       用户ID
     * @param favoriteType 收藏类型
     * @param targetId     目标ID
     */
    void removeFavorite(Long userId, String favoriteType, Long targetId);

    /**
     * 检查是否已收藏
     *
     * @param userId       用户ID
     * @param favoriteType 收藏类型
     * @param targetId     目标ID
     * @return 是否已收藏
     */
    boolean isFavorited(Long userId, String favoriteType, Long targetId);

    /**
     * 批量检查收藏状态
     *
     * @param userId       用户ID
     * @param favoriteType 收藏类型
     * @param targetIds    目标ID列表
     * @return 收藏状态Map，key为目标ID，value为是否已收藏
     */
    Map<Long, Boolean> batchCheckFavoriteStatus(Long userId, String favoriteType, List<Long> targetIds);

    /**
     * 获取用户收藏列表
     *
     * @param userId       用户ID
     * @param favoriteType 收藏类型（可选）
     * @param limit        限制数量
     * @return 收藏列表
     */
    List<FavoriteRespVO> getUserFavorites(Long userId, String favoriteType, Integer limit);

    /**
     * 统计用户收藏数量
     *
     * @param userId       用户ID
     * @param favoriteType 收藏类型（可选）
     * @return 收藏数量
     */
    Long countUserFavorites(Long userId, String favoriteType);

    /**
     * 清空用户收藏
     *
     * @param userId       用户ID
     * @param favoriteType 收藏类型（可选，如果不指定则清空所有）
     */
    void clearUserFavorites(Long userId, String favoriteType);

    /**
     * 切换收藏状态（如果已收藏则取消，如果未收藏则添加）
     *
     * @param userId       用户ID
     * @param favoriteType 收藏类型
     * @param targetId     目标ID
     * @param remark       收藏备注（添加时使用）
     * @return 操作后的收藏状态
     */
    boolean toggleFavorite(Long userId, String favoriteType, Long targetId, String remark);

    /**
     * 分页获取用户收藏列表
     *
     * @param userId       用户ID
     * @param favoriteType 收藏类型（可选）
     * @param pageParam    分页参数
     * @return 分页结果
     */
    PageResult<FavoriteRespVO> getUserFavoritesPage(Long userId, String favoriteType, PageParam pageParam);

    /**
     * 分页查询用户收藏项目（前端友好格式）
     *
     * @param userId       用户ID
     * @param favoriteType 收藏类型
     * @param pageParam    分页参数
     * @return 分页结果
     */
    PageResult<FavoriteItemRespVO> getUserFavoriteItemsPage(Long userId, String favoriteType, PageParam pageParam);

}
